PD Collection CD 1

home *** CD-ROM | disk | FTP | other *** search

/ PD Collection CD 1 / PD Collection CD 1.iso / textual / cite / support / Docs / Manual < prev next >

Wrap

Text File | 1996-03-31 | 45.7 KB | 952 lines

Citation Database Manager (v1.5) Manual ======================================== CONTENTS -------- 1. Input 1.1 - Keyboard input 1.2 - File import 1.3 - #ID numbers 2. Output 2.1 Export Icon 2.2 Field Export 2.3 Generating Citations 2.3a Defining the style 2.3b Selecting references 2.3c Generating the output 3. Searching 3.1 First Author 3.2 Record #ID No. 3.3 General Search 4. Archiving 5. Configuration & Preferences 5.1 memory_transfer 5.2 Journals 5.3 Preferences 5.3a Archive opt(ion)s 5.3b Export "and" separator 5.3c Citation "and" separator 5.3d Export type 5.3e Brackets 5.3f Medlars Abstract 6. Misc 7. Errors This package should included the following: * !Citation - Main Application. * Refsdata - example citation library, drag to the iconbar icon. * Txtdata - an example bulk import text (see section 1.2 Bulk import). * OldArch - a pre-v1.5 example archive file (see section 4. Archiving). * NewArch - a v1.5 example archive file. * Medlars - an example Medlars file. * Docs directory - containing this Manual and some !Draw files showing annotated screen shots. What follows is a brief run down of the main features of !Citation - don't be afraid to experiment using the supplied example data. 1. Input ======== "Where do I start?".... Load !Citation (double click in the icon in the filer window) and drag a library (for example "Refsdata" supplied with this package) to the !Citation icon on the iconbar (the big "C") and you will see the main viewer window display the first record in the citation library. Note that !Citation data libraries are actually application directories which can be copied, moved and *DELETED* (though not whilst it is being used by !Citation - please) as usual through the RISCOS filer menus... so keeping backups is easy. Shift-double clicking on a library (app directory) opens it to show the data files, one not surprisingly called "data" and others called "0", "1" etc. which are indexes. Do not alter these files or your data will be corrupted - but of course you will always have that back-up...?? You will also see the !Run and !Sprite files which are needed to define the resource as an application directory. "What about renaming the library?"..... Renaming these data resources has always been a bit problematical (look at CC's Impression) because the sprites in the sprite files need to be re-named as well as the directory otherwise the icon will not be displayed. Unless you are familiar with the workings of sprites and are happy with the former method, perhaps the easiest way to rename a library is to create a new library with the required name, open it, delete the empty data files and copy the full data files into the new directory. Note that it is the library directory that has a "name" not the data files. "How do I create a *NEW* library?".... Simply open up the icon bar menu, select "New Library", enter a name and drag to a filer window. Data files will be automatically created in this directory by !Citation and an empty viewer window displayed ready for data entry. The "!" prefix is automatically added to the name if you forget. If no library is loaded then the main viewer window opens with "No file open - Waiting" and advice in the Title field to "Drag a citation library to the iconbar...". Dragging a library to the iconbar immediately open the file and displays the first record. If you have several libraries, when the next is dragged to the iconbar and the current library is closed and the new one opened. "Close library" in the iconbar menu closes the current library and returns !Citation to its waiting mode. This option is occasionally useful since the pathname of the last active library is retained in a configuration file so that !Citation always opens where you left off. If this library moves or is deleted between running !Citation, !Citation will report an error and open with "No file open". If you make a back-up of the configuration file (see 5. Configuration) use the "close file" option in the icon bar menu first. This zeros the active library to "default" and prevents this error - but don't worry it is not a fatal if it does occur! 1.1 - Keyboard input -------------- We will deal with manual input first and describe the actions of the icons on the main viewer card (see also accompanying !Draw file - "viewer").... Icons at the top of the card are grouped from left to right: *Window header bar - shows the name of the active file, editing/adding modes and the number of records in the library. *Status window - shows the record #ID number. *Goto first record arrow *Goto previous record arrow - note "adjust" click on previous/next arrows jumps 10 records and "select" just one record. *Goto next record arrow *Goto last record arrow *Add a record - in this mode all arrow keys are disabled (in fact all record movements) while a new record is manually added. *Edit a record - once in this mode one can "browse edit" with arrow keys to allow easy alteration of consecutive records. This also works with secondary arrow icons in "Search" and "Generate subset" windows (see later). In browse editing mode altered records will be automatically updated if user moves to a new record (ie. clicks on an arrow in the main viewer window) but you must use "Save" on the last altered record if leaving this mode, to update the file. This also applies to the secondary arrows other windows (see below). *Delete - flags the current record as deleted. Note records are not removed until the file is "Compacted" from the icon bar menu ("Compact library") since this can be a time consuming process and best executed in bulk. No attempt is made to stop the user editing deleted records. These will be lost on the next compact but can be reinstated BEFORE compacting using the "Main menu>Misc>Undelete" option. *Cancel - abort current operation and reinstate altered fields. *Save - update any changes to disc (note comment in Edit above). Only one record is ever held in memory so that if the system crashes data loss is minimal. *Export icon allows dragging of author names directly into your paper in the appropriate format eg. "[Radulescu et al, 1986]" or "[Smith & Jones, 1801]". (see 2. Output, for difference between select/adjust drags) If no file is open then all icons are disabled. If a new, empty data file is selected then only the "add" icon functions. Now to the nitty-gritty of typing. !Citation needs to have authors entered in a specified format to provide a known starting point from which the various output formats can be derived. Authors should be entered as: SURNAME, SPACE then INITIALS with no spaces between initials eg. Brown FG, Williams ED. !Citation assumes that all the characters *AFTER* the last space separator are the initials so that double-barreled or complex surnames with several part can be used eg. Wynford-Thomas D ("D" is the initial) Yo Ti Wa XF ("XF" are taken as the initials) de Cuevas BA ("BA" are taken as the initials) Minster (Jean-Francois) J-F ("J-F" are taken as the initials) The FRAM Group ("Group" is interpreted as initials) The last example represents a special case since it is likely that the user would wish to treat this author string as as a single entity. To indicate this, all the elements of the string *MUST* be joined by a hyphen or similar unique separator thus: The-FRAM-Group or The#FRAM#Group !Citation will then handle this string as a "surname" only with no initials. The separator may then later be removed by "Search & Replace" in the final copy. Note also, that provided punctuation of Authors fields is not required (in "Author Options", Citation styles window), full first names may also be used eg. Bond James. Up to ten authors can be specified and the "et al" icon can be selected at any time to add "..., et al" to the author output. Note that this icon is automatically selected if more than 10 authors are detected on bulk input, to flag to the user that more authors exist than can be accommodated by !Citation. Each maximum author length is 23 characters for surname and initials (...technical limitations I'm afraid but should be enough for most purposes). Title and Notes fields have a 254 character limit. The source fields comprise: Journal/Book title - 55 chars Editors - 30 chars Publisher - 25 chars ISBN/Place - 25 chars volume - 10 chars pages - 15 chars date - 15 chars These are essentially free format so that dates can be 1967 or 1973a or 13th Sept 1856. Similarly, pages and volume can contain letters to allow for example supplement page numbers "s11-s45". This flexibility essentially means that there can be no validation check on these fields for, say, numerical input only. A "select" click on the menu icon which sits by the Source header brings up a menu of your preferred journals (see 5. Configuration, for information on how to edit this list). If you are in adding/editing mode then clicking on an item in this menu inserts it into the Journal/Book title field, otherwise the options are greyed out (unselectable). The Keyword field can be upto 55 characters in length and can be used in any manner you wish, with or without separators between words. "How do I start adding references?".... Clicking on the "Add" icon will clear the card ready for input. The cursor will be initially in the First Author field but can be moved to another field by clicking into it or using "Tab" or "Return" to step through fields. "Tab" will step though groups of fields so that if there is only one author to enter, "Tab" will jump on to Title whereas "Return" steps through individual fields sequentially. The left/right cursor keys move within a field and with shift or ctrl effecting larger steps. Text in the longer fields will word wrap and scroll if necessary. Shift-Tab moves to the previous field. Ctrl-U clears a field and other standard RISCOS protocols apply. "Page up/down" or shift up/down arrows will allow browsing through records, mimicking clicking on the forward/back icons with "select". Note the "Paper type" and "Copy?" icons which give a quick visual reminder to the paper type or possession of a hard copy. A format card is available, which, in the adding mode, allowing authors, title, notes, papertype, copy, etal, keywords etc. *AS WELL AS* the subset assignments (see defining subsets in section 2.3b), to be duplicated over several additions. This is accessed from the "Main Menu>Format card>Edit format". Remember to toggle this option ON with "Format card>Use format". A tick by this item in the menu indicates the format card is active. Toggle OFF after use. 1.2 - File import ----------- The file import window is accessed from the "Main Menu->File import". This window is used for three types of importing: 1) Citation archive files, dealt with later, 2) So called "Five-line text" files and 3) Medlar formatted files. The "five-line" text files are a useful option, as described in the introduction. Personally I keep a list of my current references in a text file on my Psion/Pocket book as a plain text file, adding to this list as I come across new references. This saves long typing sessions and keeps me organized...! The five-line file has the following format: start of file... au,au,au[CR] title[CR] journal_title,vol,pages,yr[CR] notes[CR] [CR] ...end of file There is a new line (CR or LF not both) after each line and after the last line of the last reference. The authors and source lines are formatted as comma separated variables and if no "notes" are included a blank line should *STILL* be present, so that there are *TWO* blank lines after the "Journal_title" line before the next reference (see the accompanying "Txtdata" file for an example). Thus there are 4 lines carrying the information and a 5th blank terminator line (this is used as a rough check that the file is in the correct format before import). The 5-line format however doesn't cater for the extra book fields in the database which will have to be entered manually. "How do I import my 5-line text file?".... Open the File import window, ensure the 5-line/Medlar is appropriately set and drag your text file into the window. (The import window only accepts CSV files, which it assumes are archives and text-type files which are assumed to be either 5-line or Medlars input depending on the button setting.) You will be informed that the file format will be checked first and given the option to continue or cancel. I have found, from experience, that despite this simple file structure it is easy to put an extra CR/LF in by mistake or forget to leave a blank line between references or a blank line for the "notes" if none are present. This would cause a synchronization error on import with fields being entered out-of-step. To prevent this Citation checks that each entry comprises 4 lines followed by a blank 5th line and if a non-blank 5th line is detected an error is flagged with an indication of roughly (+/- 1) around which entry the error lies. The file length is also checked to see if it accords with the number of entries. Lines of over 254 characters (this applies primarily to "title" and "notes" fields) are automatically truncated and ">>" added to the end to indicate this. No other warning is issued. If the format is OK then the user is asked whether to continue with the import. If a format error is flagged, check the file at the indicated place, correct the error and begin the process again. The error checking routine is fairly simple and aborts on the first error encountered. It might require several runs to debug a file that contains multiple errors but this is better than having all the fields out-of-synch. Importing occurs at about 40 references/min on an old ARM3 A410 (time for a cuppa!) but should be faster on newer models. "What about Medlars files?".... Medlar files are a standard format produced by some computerized journal databases specifically for importing into bibliography managers. I use this facility on MedLine which is the main database in the medical field but since this format is widely used by bibliography managers on other platforms (Endnote & Papyrus) I guess it is fairly universal. An example file is included with this package. Importing is through the same window but select the Medlars button BEFORE dragging the file. Confirmation for import is requested and then the whole file is directly imported on the assumption that, being machine created, there is no need to pre-check. However if you edit your file first to select out the desired references be sure to leave the individual references intact. These have a 6 character leader to each line which either contains a field assignment eg "AU - " or 6 spaces for continuing assignments. Each reference is terminated by a blank line. All these are required for !Citation to work out what goes where!! So the message is... edit with care... You will also see from the example file that I have assumed that these will be DOS files with both a CR and LF at the end of each line. !Citation will handle this automatically - there is NO NEED to strip out CRs - in fact if you do, this will mess up the routine. If you have a system that doesn't use DOS let me know and I can make a simple change to the routine to account for single LFs of CRs. "Can I replicate some fields over a series of file import cards?"... Yep.. With both types of file import, the Format card (Main Menu>Format card>Edit Format) can be used to set "papertype", "copy?" & keywords. The keyword option in particular, provides an easy means of grouping papers since a particular keyword can be searched for and autoadded to a Subset for output (see 3.3 General search). Don't forget to toggle "Main Menu>Format card>Use format" ON (ie. ticked) and untick after use. "Oh <substitute expletive>! I imported the wrong file... What can I do?" Have a cuppa and calm down... If you import the wrong batch of references or an error occurs and the file is half imported you can use the "Delete import" option from the "Main Menu>Misc>Delete import" to remove all of the last imported references and compact the file. If you have other deleted records in the file, this process also removes them - beware... Note this only works within a session. If you quit and restart !Citation the import pointers are lost. The user can also directly import text files to the Author, Title and Notes fields of the displayed record by drag'n'drop on the appropriate field. Note that this can ONLY be done in editing/adding mode. Authors should be comma separated and in the usual format. If a mistake is made "Cancel" will usually reinstate the previous text. Text also can be exported from these fields (see 2. Output) which means that !Edit can be easily used as a tool for editing long fields, re-importing after alterations. 1.3 - #ID Numbers ----------- Each reference in !Citation is allocated a unique identity number (#ID) which is indicated in the status window as "No. #xxxx". To ensure that the #ID numbers are indeed unique they are assigned sequentially as records are added. Thus for a group of records in which there have been no deletions, these #ID numbers run sequentially but as records are deleted, gaps in the sequence may appear but this is of little consequence to the user. Two options are provided to manage record #ID numbers. "Main Menu> Misc>Reset #ID No." leads to a small window which shows the #ID number which will be assigned to the next entry and allows the user to change this "seed" value. This must be done with EXTREME caution since you may well end up generating duplicate #ID numbers and there is little error checking in this routine - alterations require confirmation through a warning box. Altering this "seed" value may be of use if you need to add a group of records originating from another application (de-archive or file import) which require specific #ID numbers, though I am sure other occasions may present themselves. The other option, "Main Menu>Misc>Alter #ID No.", allows the user to alter the #ID number of the record currently shown in main viewer window. Again caution is advised but this routine checks for invalid or duplicate number or warns the user that the #ID lies outside the current range and may be duplicated later 2. Output ========= Output from !Citation can be performed in 3 ways. 2.1 - Export Icon ----------- A "select" drag from the Export Icon (green arrow, top right of main window) gives "[authors & yr]" only from the current reference shown in the card. This is useful if you have !Citation running as your are writing and want to insert the currently displayed author into the paper's text. !Citation automatically works out the appropriate author format and puts this into the paper with the year surrounded by parentheses. This should work with any type of wordprocessor/DTP package and uses file or direct memory transfer. Alternatively an "adjust" drag from export icon give full citation in the defined citation style (see section 2.3a). 2.2 - Field Export ------------ As mentioned in section 1.2, the Author, Title and Notes fields can be directly exported to file or to an application through direct memory transfer by dragging from the small green arrow adjacent to their header icons (see the !Draw file "viewer"). Note that text can be dragged directly back into those fields *ONLY* when !Citation is in the editing/ adding mode. 2.3 - Generating citations for final output to a technical paper ---------------------------------------------------------- This comprises three parts a) defining the style of the output references, b) selecting which references within the database are for output and c) generating the output set. 2.3a - Defining the Style ------------------ The essence of !Citation is the ability to output references in any desired format. Styles are set up in the the Citation style window (Main Menu>Citation style, see also the !Draw file "style") and allow any style of output using certain command words. These are (note lower case and exact spelling): Command Output ------- ------ idn Unique ID no. auth Authors in given format title Piece title sot Source (Journal/Book) title vol Volume field pgs Page field date Obvious really! eds Editor field pub Publisher field isbn ISBN/Place field keys Keywords field note Notes fields * Tab char [09] / New line [LF] They are mostly self explanatory. Any or all of the command words can be combined in any order with any punctuation or special characters (*/) as indicated above eg. auth (date)./title/{italic on}sot{italic}/vol;pgs This would output the authors followed by a space, date in parentheses followed by a full-stop, new-line, title, new-line, curly brackets containing the words "italic on" followed directly by the source and "{italic}" again. A new-line is inserted before volume number which is followed by a semi-colon and page numbers. Anything which !Citation encounters in the style format which is not a command word or */ is simply included in the output at the appropriate place eg. all punctuation (including spaces) and strings like {italic}. Note that the expressions in {curly brackets} are text formatting commands recognised by Impression which allow automatic conversion of the enclosed text into the specified style (see CC's Impression/Style manual - "Advanced Search and Replace" or set up some styles and export the text story with "Styles Set". The exported text will show the correct format). Thus in this case the "source" field will be italicized - a requirement of some journals. Three journal styles and 3 book styles, are stored in !Citation and these are saved in a configuration file (see 5. Configuration). Select which style you wish to use with the radio buttons by each style. To return to the default settings use the "Iconbar Menu>Citation styles>Default" (note this will replace your currently stored styles on exit). To restore the last saved styles to the current style window use the "Iconbar Menu>Citation styles>Restore". The Author options in Citation style window allows surname and initials to be reversed (from that shown in the viewer window), surname to be capitalized, and initials to be punctuated with a full stop, space or "#". The latter is sufficiently unusual to allow later search and replace in !Edit to convert to more esoteric separators if desired. The "With and" option allows automatic insertion of "and" or "&" (see Configuration 5.3b, 5.3c) before the penultimate author if required. Book Styles ----------- Book references often require a slightly different output format from the standard journal format so !Citation automatically detects references which are of "book" type from the "Type" setting (viz. Paper/Review/Book) in the main viewer window and uses the selected "Book" format specified in the !Citation styles window. eg. Authors: Ears BG Noddy TB Title: The role of toys in child development. J/B title: Symposium on Child Health and Development Editors: Caroll L and Seagull L Publisher: Churchill Livingstone ISBN: 1234-4569-7894 Pages: 124-134 Year: 1985 The book format of: auth (date)/title In: sot. Eds.: eds, Publisher: pub. ISBN isbn pp pgs will then output: Ears BG, Noddy TB (1985) The role of toys in child development. In: Symposium on Child Health and Development. Eds.: Caroll L and Seagull L, Publisher: Churchill Livingstone. ISBN 1234-4569-7894. pp 124-134 2.3b - Selecting references for output ------------------------------- !Citation uses the idea of "Subsets" to select which references are for output, such that any record in the file can be included in a "Subset" of references. This simply means that each record holds a flag (actually 5 flags) which indicates whether that record is a member of a particular Subset. There are up to 5 Subsets (hence 5 flags, numbered 0 to 4) and any record can be a member of any one or more of these Subsets or none. The Subset status for any record is shown in the "Define subset" window (Main Menu>Citation subsets>Define subsets, see !Draw file "subsets"). This window is an extension of the information seen in the main viewer and changes as the user browses the file. A reference is included in a Subset if the button by the Subset number (0 to 4) is ticked. The field next to this button, which contains a number will turn yellow if the corresponding set is selected - this is the "Ordering value" (we will return to this below). To select a Subset of references for output, one browses through the file to find the desired references and each time clicks on a Subset button to include that reference. With 5 Subsets, the user can have say, 5 papers on the go at any one time each defining a discrete Subset, though of course any one record may be a member of several Subsets. This method, particularly in combination with the various search options (see below), allows references to be easily added or removed from a Subset. The "Clear subset" option (Main Menu>Citation subsets>Clear subset) will clear any selected subset of ALL members - use wisely. It is thus essentially very easy to build up a Subset but what about the output order? In most cases journal require references to be arranged in alphabetical order, which can be performed automatically by !Citation but what about those that require references to be arranged in a particular order - usually the order in which the references occur in the text? This is where the "Ordering value" comes into play. This is simply a value which indicates to !Citation the order which the user would like the references to be arranged on output - note it is NOT the number which is printed by the reference on the final output but a value which simply determines the order in which references are organised in the final output. Thus the Ordering values do not need to be consecutive eg. if ref1=(10), ref2=(20), ref3=(15) the output will be.... 1. ref1 2. ref3 3. ref2 In fact the bump icons in this window can increment in steps of 1 or 10 depending on whether the are "select" or "adjust" clicked and I would recommend that the user uses large steps so that is is easy to go back an insert or reorder the references as the paper evolves. The process of setting the Ordering value is an extension of selecting the record as a Subset member. Once the Subset button is ticked the ordering field becomes available (ie. goes yellow). You should see the cursor in this field, if not click in it to put the cursor there, then either use the bump icons to increment/decrement the value (0 to 999) or enter a value manually. One only needs to click on the "Save" icon (bottom right of the card) if manually inputting a number into Ordering value. Clicking on the bump icons updates the record automatically. Once the Ordering value is given move on to the next record...and so on. Note that if the user only requires an alphabetical output the Ordering value can be ignored. The Subset selection buttons or Ordering values for a record can be changed at anytime and are stored with the record until the Subset is cleared. 2.3c - Generating the output subset ---------------------------- We now have a citation output style and a Subset (or more) defined and we can output the Subset to the paper. Opening the Main Menu>Citation subsets>Generate set window shows the 5 possible subsets, the Order options, Go, Clear and Arrow icons (see !Draw file "subsets"). First select the Subset for output using the "Subset" radio buttons and then the desired output order. This is "plain Alphabetical", "Numbered alphabetical" and "Ordered" ie. according to the Ordering values. Click on the "Go" icon and !Citation searches the database to collect together all records which are members of that subset. The arrow keys can now be used to browse through the set to check the order and membership. The status window in this card indicates the browse position in the Subset. Note that once !Citation has calculated this group, altering the membership of the Subset with the "Define set" window has no effect until the process is "Clear"ed and started again. The final step is to click on the Generate subset icon (blue icon by the status window) and a save box is shown for the user to drag the set to file or directly into the paper. 3. Searching ========= Three forms of searching are supported a) First Author, b) Record #ID number and c) General Search (see !Draw file "search"). 3.1 - First Author ------------ !Citation maintains an index of First author names as they are entered which allows very rapid searching. Opening the search window (Main Menu>Search>1st author) shows a yellow string entry field. Click in this field and begin entering the surname. Each letter is grabbed by !Citation as it is entered and the file updated to the nearest match. If the sequence of letters thusfar entered (which need not necessarily be the whole name) is not found then !Citation bleeps and flags "Not found" in the main card status window. The arrow keys on the search card allow alphabetical browsing of the file either around your found surname or if the field is empty, through the whole file. The user can, in this way, search for an author and once found browse round related papers. If there appears to be a problem with the alphabetical ordering it may be because the author index has become outdated. This shouldn't often happen but may occur after multiple file imports and deletes. In this case re- index the file using the "Re-index" option on the iconbar menu - this doesn't take long. An out-of-date index does not affect the "Generation subset" option since this creates its own new index each time. 3.2 - Record #ID No. -------------- This simply accesses any record by its unique #ID number so that the user can go directly to any reference. The card number is entered into the entry field and pressing <Rtn> activates the find. 3.3 - General Search -------------- For more extensive searches, including all Authors, Keywords, Sources and Subject (ie. Title, Keyword and Note fields combined) use the general search option (Main Menu>Search>General Search). The "Search range" on the general search card is self evident. "Authors" searches ALL authors (unlike the first author search). "Subject" searches Title, Keywords and Notes for the search string. "Keywords" searches keywords only - useful for defining a Set. The search string is case independent and the search performs a simple - "does the field specified in the search range *contain* the search string". This window bears some similarities in function to the "Generate subset" window in that a search string is entered and "Go" clicked (pressing <Rtn> after typing the search string mimics clicking on "Go"). The number of finds is flagged in the status window and the arrow icons allow browsing (and editing) through the found records with the status window indicating the position of the record in the found group. Before entering another search string the current search needs to be cleared with the "Clear" icon. Searching with an empty search string selects all records. This could be useful if you wish to output all references in a file, perhaps to import to another application (note that there is also an archive option which produces a CSV output of the entire file, see section 4.). Defining the citation style with commas or tabs separating fields allows a CSV or TSV formatted output (TSV though obviates any problems with the commas separating authors). The "Autoadd" option adds all finds to a specified Subset but does not provide an Ordering value. This is useful if the user has a group of records characterized by a specific term in the subject or keywords fields. These can be searched out and added to a Subset ready for output. An ordering value can be added by selecting the Subset using the "Generate subset" option with alphabetical ordering and stepping though the Subset updating the Ordering value as necessary. 4. Archiving ============ Selecting "Archive" from the iconbar menu archives the main fields (ie. Author, Title, Source, Year) of the *ENTIRE* current library into a CSV format file. It is also possible to include the other ancillary fields usually held in a Citation record, viz. identity number, notes and button fields into the file by altering the "Archive opts" in the "Icon Bar Menu -> Preferences..." window (see section 5.2 for Archiving options). The button fields, "etal", "papertype" and "Copy?", are converted to text values in the process (ie. to etal_on/off, copy_on/off and research/ review/book - see example Archive file) to make the file more readable. In contravention to the CSV standard, the archive file carries a one line header which provides general information on the creation date etc. but more importantly for Citation, specifies the presence of ancillary fields. This header shouldn't cause much of a problem in general use and can be deleted if the archive is not intended for use with Citation (see Technical info below). The archive options are by default set to include all fields except the identity numbers which is a suitable configuration for the following operations. The first major use of archiving is for the combining libraries. Simply load and archive each of the libraries you wish transfer, then open the receiving library and drag the CSV archive files to the file import window (Main Menu->File import). !Citation will detect that this is a CSV archive file (rather than a 5-line text or Medlar file) and a warning will be flagged asking for confirmation of dearchiving. If accepted the archived data will be added to the end of the receiving library data with new ID numbers allocated. The second major use is for "future-proofing" !Citation. Should a later version of !Citation require a change in the structure of the data file then data can simply be archived out of the old version and imported into the new version. If it is necessary to preserve the unique identity numbers of your old library, set the archive option accordingly (see section 5.2 for Archiving options). Other possible uses include, of course, importing of the whole file into any application that accepts CSV format files and importing CSV data into !Citation. In the former case, remember to delete the one line header or substitute it for a CSV description header before importing into your alternative application. Importing a CSV file into !Citation, could be problematic. !Citation expects the file to be machine created and so minimal error checking is employed on de-archiving. As you can see from the example Archive file (load it into !Edit), it is quite complex and easy to make errors if manually created. The only advantage of this type of import over the 5- line text type (see section 1.2 File Import) is again the ability to include "button" fields and keywords in the data. If you do attempt CSV import, make a backup of the receiving library first! Technical info -------------- If you intend just use the Citation Archive files within Citation ignore the following section. If you wish to import CSV files from another application then you will need to know how to provide a header with the information Citation needs to make sense of the file. A header created by Citation will look something like this... "Citation Archive file. Created: 31/08/95.19:22:55 Ancillary Fields: keywords, notes, buttons" ... and it is all quite simple really. Citation first checks for the presence of the string "Citation Archive" in the header (note this is case sensitive). This is to trap incompatible files, so that in creating your own a header, this string must be present somewhere in the header line. The creation date and " Ancillary fields:" string are not validated and can be ignored. Secondly, Citation assumes that the CSV file contains at least the standard fields of 10 authors, title, source, volume, page and year. If ancillary fields are to be included then the following strings must be included in the header for each field present: "#IDN" - for the identity number "keywords" - for 5 keyword fields "notes" - for the notes field "buttons" - for the 3 button fields "etal", "papertype" and "copy" The order of the fields and format of the button values are obviously important and can easily be gleaned from examining the example archive file. Thus to import a CSV file containing references with a unique ID no. and keywords, a suitable header would be: "Citation Archive #IDN keywords" I hope this is sufficient explanation but since this is a subject which is only likely to be of interest to a minority of users it doesn't warrant a voluminous exposition. You are welcome to Email me for more info. 5. Configuration & Preferences ============================== There are 3 configuration files in the !Citation application directory (to open Shiftdouble click on !Citation), namely "config", "settings" and "options". "config" is used by the SBase exec program which runs !Citation (which is in intermediate code) - this file should not be changed. "settings" is similarly sacrosanct! This file is read by !Citation on start up and is updated on closing the application. It holds your preferred citation styles (amongst other things) and if this file is corrupted or lost !Citation will report an error on startup and uses defaults. A new 'settings' file will be created on exit but your previous styles will be lost. You may like to keep a back up. The last active file is also stored here, so if this moves or is deleted between running !Citation, !Citation will report an error on next start- up and open with "No file open". If you make a back up of this file use, the "Close library" option in the icon bar menu first, which zeros the active file to default and prevents this error - don't worry it is not a fatal error if it does occur! The "Citation styles>Default" option on the icon bar menu deletes all your preferred styles and returns to the defaults. Your preferred styles will be lost - beware (but may be restored with "Citation styles> Restore" before exiting). The "options" file however, is fair game for alteration by loading into !Edit. It needs a bit of explanation first, but essentially looks like this: File Start..... ***** Options - change carefully. See manual ***** memory_transfer ON ***** Add Journals Below ***** Nature Science J. Endocrinol Mol Cell Biol *END* ...File End The "Options" section contains (at the moment just one) configuration features which will rarely need altering once set up. Please alter only the appropriate parts (eg. ON/OFF). Adding lines (journal names excepted) or changing the order may have unexpected effects. Note that alterations to these options only take effect when !Citation is run. 5.1 - memory_transfer ON/OFF (default ON). ------------------------------------ A problem has been reported with direct drag'n'drop memory transfer to other applications (eg. dragging from the "Export" icon to a WP) causing !Citation to crash - in particular to earlier versions of !Techwriter. The cause of this is, in the case of !Techwriter, rather technical but one (possibly slightly inelegant) solution is to avoid memory transfers altogether and use the <WimpScrap> directory instead - hence this option. With memory_transfer OFF, Drag'n'Drop works just as with before but your disc will spin up. The disadvantages are that it is a little slower and you really do need a hard drive. No problems with memory transfer have been found with !Edit, !Zap, !Artworks, !Style, !Publisher, !Draw(+) and for the most part you can leave the option ON. (My thanks to Peter Killworth and the folks at Icon Technology for their help with this one.) Note the latest version of Techwriter should now work with memory transfer. 5.2 - Journals -------- A list of your favourite journals can be included in this file below the indicated "*****" separator. These should be entered as one journal per line with no empty lines between journal names and do not remove the "*END*" marker. Any number of entries may be added but the sum total length for the whole list cannot exceed 255 characters. Entries over this limit will be ignored. 5.3 - Preferences ----------- A preference window can be called up from the icon bar menu which allows the setting of various parameters whilst Citation is running. All but the Archive opts are saved in the "settings" file on exiting the application. There is no "OK" icon in this window since all options are immediately effective and it is closed by clicking elsewhere or on the close cross. 5.3a - Archive opt(ion)s This allows selection of the ancillary fields to be included in an archive file (see section 4. on Archiving). These settings are *NOT* saved on exiting and will always default to ID no. OFF, keywords ON, notes ON and buttons ON on starting the application. This is to try and obviate the possibility of accidentally saving an archive with ID nos set and creating duplicates. Note that the warning box which asks for confirmation of de-archiving also shows which ancillary fields (if any) have been flagged in the header line. 5.3b - Export "and" separator A select drag from the "Export" icon (section 2.1) can be used to put the author name and year in a document. The default setting for a two author entry is [Smith & Jones, 1995] ie. using the ampersand symbol as a separator. This option setting may be changed, if desired, to give the letter form ie. [Smith and Jones, 1995]. 5.3c - Citation "and" separator An option is available in the Author formatting in the Citation style window to place an "and" separator before the penultimate author name viz. Henery GH, Williams DW, Jones FG and James DS. The default setting is the letter form of "and" but may be changed to the ampersand symbol, if required, by altering this option setting accordingly. 5.3d - Export type A select drag from the "Export" icon (section 2.1) can be used to put the author name and year in a document. Selecting "#IDN" prefixes this output with the reference ID number eg. [#0234-Smith & Jones, 1995]. This is mainly intended for automatic citation generation (not implemented in this version) but might also prove useful for quickly back-referencing from the manuscript. 5.3e - Brackets A select drag from the "Export" icon (section 2.1) can be used to put the author name and year in a document. The default setting is to enclose this string in square brackets but round or curly brackets can be selected with this option. 5.3f - Medlars Abstract Medlar file abstracts are generally quite long and don't fit into the "Notes" field without considerable truncation thereby making them fairly useless. Unticking this option causes !Citation to ignore the abstract section of a Medlar reference and leave the space for your own, more succinct notes! 6. Misc ======= * Note that "Compact"ing the library (icon bar menu) closes any active Search or Subset queries first since these may contain references which are flagged deleted and therefore removed from the file. Use this option cautiously. * The "Delete all records" option in the icon bar menu does just that for the entire library...do keep regular backups of your data. * There are some hot keys which work ONLY when the main card has the input focus: ctrl-D, open Define Subset window ctrl-S, open General Search window ctrl-A, open First Author search window ctrl-N, open Record by #ID no. ctrl-G, open Generate Set window * Clicking on the close cross - top left of the main viewer window, hides this window as well as any other window related to !Citation. The file is NOT closed and "select" clicking on the iconbar icon reopens the main viewer window and any related windows (search, define subsets etc). This is useful for maintaining an uncluttered desktop whilst working on your WP and you can easily flick back and forth to insert citations. * Most database files (including this one) use fixed length fields. A record uses about 1kb so a fair sized library can be stored on a 1.6 Mb floppy for backup (say, over a 1500). However, since most records contain numerous redundant spaces a compression utility (!Spark, !Compression etc) will achieve significant a space saving. 7. Errors ========= I have tried to prevent most errors occurring by design but those obvious ones which escape are covered by appropriate error handlers (usually where data is imported or exported and the media may be faulty/not present). Error reports are mostly informative but S-base exec does not support many error messages so you might get something like "Error 107" or similar. A click on "OK" will abort most errors and !Citation will fail-safe. A global error handler, however, is provided to capture unforeseen errors and flags, "!Citation has encountered a fatal error and must exit immediately. No data should be lost (see manual)." After exiting, !Citation then writes an error code to the "settings" file (see section 5.). Immediately after experiencing such an error (preferably before running !Citation again), make a copy of your "settings" file and send it to me for diagnosis. Happy writing....